NOTICE:
The Arnor products for the Amstrad CPC and Amstrad PCW
are  Copyright 1997-2001 Brian Watson. All rights reserved
For support and printed manuals for these products please contact Brian at:
  Brian Watson,
  "Number Six",
  Windmill Walk,
  Sutton,
  ELY
  Cambs
  CB6 2NH
  ENGLAND
or
  brian@spheroid.demon.co.uk
Brian Watson has given permission for this document to be made available
through the "Unofficial Amstrad WWW Resource". The original document was
provided by Richard Wildey, then scanned and OCR'ed by Kevin Thacker.


PROTEXT TECHNICAL INFORMATION
=============================

Introduction: how the PROTEXT workspace is organised
----------------------------------------------------

As a sideways ROM, PROTEXT takes 512 bytes for its own workspace when it is
initialised. The location of this workspace depends on the number and
positioning of other sideways ROMS, so any references to this workspace must
be dynamically evaluated. The IY register is set by the firmware to contain
the start of this workspace when PROTEXT is entered, so the IY-relative
instructions can be used. However, this is VERY inconvenient when coding the
program, so PROTEXT uses a different technique. A static workspace area is
chosen (at present this is &AC00, which is the start of the BASIC workspace).
Whenever PROTEXT is entered the contents of this static workspace area is
swapped with part of the dynamic workspace area (pointed to by IY). On exit
from PROTEXT they are swapped back again. This does not affect BASIC because
the BASIC memory is always restored before BASIC needs it. The advantage is
that the coding of PROTEXT is much easier, and the resulting code is probably
considerably shorter.

There are four sections to this documentation:

  1. calls that can be made to PROTEXT which either return some information
     or perform some function.
  2. vectors that may be intercepted to change the operation of some feature
     of PROTEXT or to add a new feature.
  3. printer driver format.
  4. PROTEXT key translation table


(i) CALLS
---------

Each routine has a number. Routine n is called by executing the external
command CTRL-P n (i.e. the two character name 16 n). The firmware routine
KL FAR PCHL may be used.

Care must be taken that the PROTEXT workspace has been swapped into the static
area before calling routines 5 to 12, or before changing vectors. If this is
not the case the SWAPIN routine must be called first and the SWAPOUT routine
afterwards. The rules for determining whether this is necessary are:

  1. if your code has been called as an external command, or has been called
     in any way from outside PROTEXT you will need to use SWAPIN and SWAPOUT.
  2. if your code has been called by intercepting a vector then do not use
     SWAPIN and SWAPOUT.

For all these calls PROTEXT version 1.00 or later is required.

  n  name         input       output and effect
  ----------------------------------------------------------------------------
  0  PROBE        none        CHL=version number
                              DE=dynamic workspace address
                              B=static workspace address (high byte)
  1  SWAPIN       none        Swaps workspace areas - to put PROTEXT workspace
                              in static area.
                              Flags: NC if not enough memory to run PROTEXT.
  2  SWAPOUT      none        Swaps workspace areas - to return PROTEXT
                              workspace to dynamic area.
  3  VECTORS      none        HL=address of first vector.
  4  ENVIRONMENT  none        HL=address of environment.
                              BC=length of environment.
  5  LOCATE       DE=mem_addr Sets current page/line/column corresponding
                              to address within text.
  6  SET_LINE     DE=line     Sets current line number.
  7  SET_COLUMN   DE=column   Sets current column number.
  8  INSERT       DE=number   Insert a number of spaces at the current position.
                              HL=current position (address)
                              Flags: NC if not enough memory.
  9  DELETE       DE=number   Delete a number of characters forwards from the
                              current position.
  10 GET_TEXT     none        HL=start of text
                              DE=end of text
  11 reserved     -           -
  12 GET_CURSOR   none        HL=current position (address)
  13 GET_COMMANDS none        HL=address of PROTEXT command table
                              (each command is followed by its abbreviation)
                              DE=jump table (2 bytes addresses)


(ii) VECTORS
------------

The addresses of the vectors are given as an offset to the address returned
by the call CTRL-P 3. User routines called via these vectors should preserve
the ROM states and selection and, except where indicated, preserve all
registers (especially IX and IY!).

These vectors are present in PROTEXT version 1.00 or later.

  addr name        description
  0    DRIVER_ADDR Contains two byte address of the printer driver in memory.
  2    DRIVER_LEN  Contains two byte length of the printer driver in memory
                   (by default this is &100).
  4    PRONVEC     This address is called at the start of any PRINT command
                   (P, PS, PF, PB, etc.). It initially contains a RET
                   instruction, and can be changed to any 3 byte instruction
                   (esp. JP, RST 3, etc. ).
                   The new routine may corrupt AF, BC, DE, and HL.
  7    PROFFVEC    This is similar to PRONVEC and is called at the end of any
                   PRINT command. The new routine may corrupt AF, BC, DE, HL.
  10   PRINVEC     This is called to print every character. It initially
                   contains a jump to the PROTEXT routine, and can be changed
                   to jump to a substitute routine, or to a routine which does
                   something before printing and then jumps to the PROTEXT
                   routine (the address of which was saved when the vector was
                   intercepted).
                   Entry conditions are as follows:
                    A=character to print.
                    D bit 0 is set if PRINT (to printer).
                    D bit 1 is set if PRINTF (to file).
                    D bit 2 is set if PRINTS (to screen).
                   If the routine completely replaces the PROTEXT routine it
                   should return flags as follows:
                    C       if successful.
                    NC, NZ  to retry (e.g. printer not online).
                    NC, Z   to abort printing.
                   Alternatively, jump to the PROTEXT routine, preserving all
                   registers (careful with the ROM state!).
  13   FINDVEC     Called when COPY is pressed for next find. Initially
                   contains a RET instruction.
  16   COMMVEC     Called before PROTEXT processes a command (command mode).
                   Initially contains RET.
                   Entry conditions:
                    HL=address of command string, terminated by zero.
                   Exit conditions:
                    C, Z    if command processed, return to command mode.
                    NC      if command processed, enter edit mode.
                    C, NZ   if PROTEXT should interpret command. All registers
                    must be preserved.
  19   EDITVEC     Called to interpret edit mode command. Initially contains
                   jump to PROTEXT routine. Enters with A=character from
                   keyboard. Can be intercepted to add command. Currently
                   CTRL-U, and CTRL-Y are unused. New routine must jump to
                   PROTEXT routine if it is not acting on the character so
                   that PROTEXT performs the command normally.
  22   READVEC     Called to read command string. Initially jumps to PROTEXT
                   routine.
  25   SCSYNVEC    Stored command syntax check. Initially contains RET. Called
                   during pre-printing syntax check. Can be intercepted to add
                   stored commands.
                   Entry conditions:
                    HL=address of first byte of string after stored command name
                    (i.e. after >XX). To check the command the routine must:
                      1. step back from HL until it finds one of: 0 (start of
                         text) , &A (line feed) , &8A (soft line feed).
                      2. Move forwards ignoring &80-&89 (place markers) and
                         &8B,&8C (block markers).
                   Exit conditions:
                    C=1 if command recognised. Otherwise PROTEXT will check
                        its own list of stored commands.
  28   SCPRINVEC   Stored command processor. Initially contains RET. Called
                   during printing.
                   Entry conditions:
                    HL=address of first byte of string after stored command
                       name (i.e. after >XX).
                   Exit conditions:
                    HL=address of next byte in text to be printed/interpreted.
                    All other registers preserved.
                   So if the command is not intercepted, return preserving all
                   registers. If the command is acted on, return with HL
                   pointing to the first byte of the line after the stored
                   command line.


(iii) PRINTER DRIVER FORMAT
---------------------------

An enlarged printer driver can be set up by changing the DRIVER ADDR and
DRIVER LEN (see VECTORS, above). The driver must be at least 256 bytes long.
  byte    default description
  0-1     20      Offset of first redefined character.
  2-3     94      The number of free bytes in the printer driver.
  4-5     0       Reserved
  6       66      Page length
  7       3       Top margin
  8       2       Header margin
  9       2       Footer margin
  10      3       Bottom margin
  11      1       Flags. Effect if bit set:
                    0=continuous printing, 1=Page number at top
                    2=Page number at bottom, 3=form feeds on, 4=NLQ on
                    7=New page after print
  12      5       Even side margin
  13      5       Odd side margin
  14      1       Line spacing
  15-16   1       Start page number
  17-18   65535   End page number
  19      1       Number of copies
  (20)    Character definitions.
          Each definition takes the form: ASCII code being redefined, length
          of code sequence, code sequence.
          A zero byte marks the end of the definitions.

Followed by:

Printer control code definitions.
There are 27 of these: @, then a-z.

Each code consists of a sequence of codes for off, followed by a sequence
of codes for on. Each sequence is preceded by the length of the sequence.
If a code is undefined there are two zero bytes, if there is an on code
and no off code there is a zero byte followed by the sequence for on.

The end of the table is marked by -1.


(iv) PROTEXT key translation table
----------------------------------

The default key translation table is not suitable for PROTEXT to use because
various key combinations return the same tokens (e.g. COPY and SHIFT-COPY),
while PROTEXT needs different tokens. The tokens listed below can be put in
function key expansions to enable the easy entry of a string of PROTEXT
commands.

  CTRL-@  0       CTRL-[          27
  CTRL-A  1       CTRL-\          28
  CTRL-B  2       CTRL-]          29
  CTRL-C  3       CTRL-          30
  CTRL-D  4       CTRL-0          31
  CTRL-E  5       CTRL-<          2
  CTRL-F  6       CTRL->          31
  CTRL-G  7       COPY            &E0
  CTRL-H  8       CTRL-TAB        &E1
  CTRL-I  &ED     CTRL-hyphen     &E3
  CTRL-J  10      SHIFT-TAB       &E4
  CTRL-K  11      SHIFT-CLR       &E5
  CTRL-L  12      CTRL-CLR        &E6
  CTRL-M  &EE     CTRL-/          &E7
  CTRL-N  14      CTRL-DEL        &E8
  CTRL-O  15      SHIFT-COPY      &E9
  CTRL-P  &E2     CTRL-COPY       &EA
  CTRL-Q  17      CTRL-space      &EB
  CTRL-R  18      SHIFT-ENTER     &EC
  CTRL-S  19      CTRL-ENTER      &EC
  CTRL-T  20      cursor-up       &F0
  CTRL-U  21      cursor-down     &F1
  CTRL-V  22      cursor-left     &F2
  CTRL-W  23      cursor-right    &F3
  CTRL-X  24      SHIFT-up        &F4
  CTRL-Y  25      SHIFT-down      &F5
  CTRL-Z  26      SHIFT-left      &F6
                  SHIFT-right     &F7
  ESC     &FC     CTRL-up         &F8
                  CTRL-down       &F9
                  CTRL-left       &FA
                  CTRL-right      &FB

Copyright (c) Arnor Ltd., 1985 Issue 3 06/12/1985
